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Declarations and Equates 

Transfer vector and Service Definitions 

Change Mode Dispatcher Vector Block 

Kernel Mode Dispatcher 

Intercept system service $SSI_USSK user system service 
Intercept system service $SSI_USSU user system service 
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SRHKHHKETHETHHTEKEKEHRHATHTHHAAeeeeeKeeeeaaeaereterertetererereeeeeereseeeeTete 


COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 
ALL RIGHTS RESERVED. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
IN eet WITH THE TERMS SUCH LICENSE AND WITH THE 


e 
* 
* 
* 
* 
. 
* 
* 
$I . 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY ® 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS WHEREBY * 
* 

+ 

* 

a 

. 

* 

. 

* 

* 

* 

® 


TRANSFERRED. 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 


SSSSSSSSSssss 
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HOUL 
CORPORATION. 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


2323S 
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Abstract: 
This module is the interface routine for privileged shareable 
image DBGSSISHR.EXE. DBGSSISHR defines the dispatcher and 
calls the routines to set up system service interception. 


Modified by: 
Ping Sager 


Origin: 
SYSSSYSROOT: CSYSHLP.EXAMPLESJUSSDISP.MAR 
This module contains an example dispatcher for user written 
system services along with several sample services and a user — 
rundown example. It is a template intend to serve as the starting 
point for implementing a privileged shareable image containing your 
own services. When used as a template, the definitions and code 
for the sample services should be removed. 


SoOoOoooooooooooSoscfao 
OOOCoooooooocooooo 


Overview: 
sed written system services are contained in privileged shareable 
mages that are Linked into user program images in exactly the 
same fashion as any shareable image. The creation and installation 
of a privileged, shareable image is slighsty different from that 
of an ordinary shareable image. These differences are: 


OOOoOOoOooooo 


1. A vector + Mieaes the entry points and providing other 
ontrol information to the inage activator. This vector 
EF lowest address in an image section with the VEC 

attribute. 


PAA BP BBE EEE PW nnononononononinty 2 2 2 
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2. The shareable image is Linked with the /PROTECT option 
that marks all of the image sections $0 that they will 
“ actos and given EXEC mode ownersh 

ctiv ° 


3. The shareable image wee e installed /SHARE /PROTECT 
with the INSTALL utility in order for the image activator 
te sonmees the privileged shareable image to the change mode 
spatchers. 


p by the image 


A privileged shareable jnoge implementing user written system services 


3 H is comprised of the following major components: 
71 1. A transfer vector containing all of the entry points and 
7 collecting them at the lowest virtual address in the shareable 
0 7 image. This formalism enables revision of the shareable 
0 74 image without necessitating the relinking of images that 
: e use it. 
0 7 2. A Privileged Library Vector in a PSECT with the VEC attribute 
0 78 that describes the entry points for dispatching EXEC and 
7 KERNEL mode services along with validation information. 


3. A dispatcher for kernel mode services. This code will 
be called by the VMS change mode dispatcher when it 
fails to recognize a kernel mode service request. 


4. A eh pty for executive mode services. This code wiil 
be called by the VMS change mode dispatcher when it fails 
to recognize an executive mode service request. 


5. Service routines to perform the various services. 


The first four components are contained in this template and are 
most easily implemented in MACRO, while the service routines can 
be implemented in BLISS or MACRO. Other banguages ney be usable 
but are not recommended -- particularly if they requ re runtime 
supers routines or are extravagant in their use of stack or are 
unable to generate PIC code. 


SSSSSSSSSSSSSSSSSSSSSSSSES 
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This example is position-independent (PIC) and it is good practice 
to implement shareable images this way whenever possible. 


Link Command File Example: 


$! 
$: Command file to Link User System Service example. 


$ LINK/PROTECT/NOSYSSHR/ SHARE =USS/MAP=USS/FULL SYSSINPUT/OPT IONS 

Options file for the Link of User System Service example. 
SYSSSYSTEM:SYS.STB/SELECTIVE 

; Create a separate cluster for the transfer vector. 


OOOoooooooooooocoo 
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rans et 88; $9; My DEBUG. SRCIS 
CLUSTER=TRANSFER_VECTOR, ,,SYSSDISK:(IJUSSDISP 
GSMATCH=LEQUAL,1,1 
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Pe} 
-SBTTL Declarations and Equates 
Include Files 


DEBUG.SRCISSIDISP.MAR; 1 (1) 


EXTERNAL SSIK_START 
SEXTERNAL SSIUTSTART 
SPRVDEF 

SPSLDEF 

SOPDEF 


Macro Definitions 


DEFINE SERVICE = A macro to make the appropriate entries in several 
different PSECTs required to define an EXEC or KERNEL 
mode service. These include the transfer vector, 
the case table for dispatching, and a table containing 
the number of required arguments. 


DEF INE_SERVICE Name, Entry_Point ,Number_of Arguments ,Mode 


-MACRO DEFINE SERVICE NAME ,ENTRY ,NARG=0 ,MODE=KERNEL 

PSECT $SSTRARSFER_VECTOR, PAGE ,NOWRT EXE ,PIC 

eALIGN QUAD 3 aie entry points for speed and style 

- TRANSFER NAME 3; Define name as universal symbol for entry 
3; Use entry mask defined in main routine 

-MASK ENTRY 


° IDN MODE ,KERNEL 
aT #<KCODE_BASE+KERNEL_COUNTER> 3; Change to kernel mode and execute 


; Return 
KERNEL_COUNTER=KERNEL_COUNTER*+1 ; Advance counter 


-PSECT KERNEL_NARG,BYTE ,NOWRT ,EXE ,PIC 
TE NARG 3; Define number of required arguments 


.PSECT USER_KERNEL_DISP1,BYTE,NOWRT EXE PIC 
WORD E 


“ues +ENTRY-KCASE_BAS ; Make entry in kernel mode CASE table 
ii IDN MODE ,USER 

JMP ENTRY+2 

-PSECT USER_NARG,BYTE ,NOWRT EXE ,PIC 

| NARG ; Define number of required arguments 


-ENDM = DEFINE _SERVICE 


Equated Symbols 


SPHODEF ; Define process header offsets 
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00000000 
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178 SPLVDEF ; Define PLV offsets and values | 
: SSSDEF ; Define system status code 
! ? : Initialize counters for change mode dispatching codes 
1 ; KERNEL. COUNTER=0 ; Kernel code counter 
188 
: § ; Own Storage 
1 : -PSECT KERNEL_NARG,BYTE NOWRT ,EXE PIC 
189 KERNEL_NARG: Base of byte table containing the 
+ ; number o required arguments. 
138 -PSECT USER_NARG,BYTE ,NOWRT,EXE,PIC 
132 USER _NARG: 


00004088 


001 
001 
it 
3 
001 
001 
001 
001 
001 
001 


oo 


WR 9 ODNOA UNE WN 9 OO NOA UNE OOONOUE UO 00 
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-SBTTL Transfer Vector and Service Definitions 


- 
— 


enables some upfeting of the shareable image containing coun without necessitating 
t proyrens that call them. The PSECT conte ninng the trensfer . 


a re-link of a 
vector will be posit onee at the lowest virtual address 
and so long as the transfer vector is not re-ordered, programs Linked with 
one version of the shareable image will continue to work with the next. 


Thus es additional services are added to a privileged shareable image, their 
definitions should be added to the end of the following List to ensure that 
rograms using prev ous versions of it will not need to be re-linked. 

© completely avoid relinking existing programs the size of the privileged 
shareable image must not change so some padding will be required to provide 
the opportunity for future growth. 


DEFINE_SERVICE SSI_USSK,INT_SSI_USSK,1, KERNEL 
3; Service to setup intercept 
3 system service 

DEFINE SERVICE SSI_USSU, INT_SSI_USSU,4,USER 
; Set up to use intercept 


3 systerm service in user mode 


The base values used to generate the dispatching codes should be negative for 
user services and must be chosen to avoid overlap with any other privileged 
shareable images that will be used concurrently. Their definition is 
deferred to this point in the assembly to cause their use in the preceding 
macro calls to be forward references that guarantee the size of the change 
mode instructions to be four bytes. This satisfies an assumption that is 
made by for services that have to wait and be retried. The PC for retryin 
the change mode instruction that invokes the service is assumed to be 4 by 


es 
less than that saved in the change mode exception frame. Of course, the particula 


service routine determines whether this is possible. 


CODE_BASE=16568 ; Base CHMK code value for these services 


> 


i 
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pa -SBTTL Change Mode Dispatcher Vector Block 


$3} pug =D1SP 


This vector is used by the image activator to connect the privileged shareable 

image to the VMS change mode dispetcher. {he offsets in the vector are self- 
tion sndopendens images. The system 

ersion number will be used 7 re image activator to verify that this shareable 


mage was Linked with the symbol table for the current system. 


relative to enable the construction of posi 


) ee 


G2 
00 43 ; Change Mode Vector Format 
Ba 

P+ See NMI nanaE De woOoenenaneonmeasue cea nsewoaae 

¢$ 3 : vector Type Code ! = PLVSL_TYPE 

r 3 ; (PLVSC_TYP_CMOD) H 

tS : : System Version Number ! PLVSL_VERSION 

30 : ! (SYS$K_VERSION) i 

5 : Kernel Mode Dispatcher Offset } PLVSL_KERNEL 

36 3 } Exec Mode Entry Offset PLVSL_EXEC 

28 3 } User Rundown Service Offset PLVS$L_USRUNDWN 

60 : $accaseesecassennscscessessesasesenensecasen} 

o ; Reserved 

64; ' RMS Dispatcher Offset ° PLVSL_RMS 

65 ; ; : 

e ; Address Check t  PLVSL_CHECK 


-PSECT USER_SERVICES PAGE ,VEC,PIC .NOWRT ,EXE 


74 -LONG PLVSC_TYP_CMOD ; Set type of vector to change mode dispatch 
75 LONG SYSS$K-VERSION : Ident ty system version 
7 -LONG KERNEC_DISPATCH-. ; Offset to kernel mode dispatcher 
7 - LONG ; No executive mode dispatcher 

0 LEANUP_SSV-. 3; User rundown service to restore SSV 

NG ; Reserved. 
ONG 3; No RMS dispatcher 
; Address check - PIC image 


<v | 


_——_—_—_—_——— 
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-PSECT USER_KERNEL_DISPO,BYTE, NOWRT, EXE ,PIC 

Kernel access violation 

Set pecees violation status code 

and return 
Kernel. Tau ttetont arguments. 
— Fh - e code an 


4¢4! 3 3 -SBTTL Kernel Mode Dispatcher 
dg ; Input Parameters: 
dg : (SP) = Return address if bad change mode value 
ih ; RO = Change mode argument value. 
i ! ; R4 = Current PCB Address. (Therefore R4 must be specified in ail 
Doet ; register save masks for kernel routines.) 
0020 : AP = Argument pointer existing when the change 
dg ; : cole Instruction was executed. : 
if : ; FP = Address of minimal call frame to exit 
Wits! : the change mode dispatcher and return to 
Doet ; the original mode. 

K 


& 
o 
Cc 
<= 
— 
° 


“WOVZUL #SS$_ACCVIO,RO 


KINSF ARG: 
MOVZWL #SS$_INSFARG,RO 


= 
a 


D009 RET 
DOOA KNOTME: RSB ase. to "forward request 
JUUE 
DC 10 KERNEL Pier cats 3; Entry fo dispatcher 
51 B6F48 £° DC 1 MOVAB W"=KCODE BASE (RO) ,R1 ; Normalize dispatch code value 
F 001 1 BLSS 3; Branch if co e value too low 
01 51 e 001 1 CMP R1 AKERNEL COUNTER 3; Check ie mit 

F3 oe 001 BGEQU KNOTM : Branch i? out of range 
ie 3 
0017 16 ; The dispatch code has now been verified as being handled by this dispatcher, 
DC 3 now the argument List w e probed and the required number of arguments 
1017 1 h li ill b bed and th ired b f 
dts ! 3 verified. 
ue 3 

51 Q000°CF41 9A 0017 MOVZBL W°KERNEL NARGCR1],R1 —; Get required argument coun 
51 00000004 9F41 ODE 0010 MOVAL ompute byte count inetuding, arg count 
4! IFNORD R1 CAP) RACCY vIO Branch i oreeist not readable 
BF4B'CF40 6C 91 0028 CMPB CAP) we <KERNEL anced BASESTRO heck for required number 

7} 1F OC BLSSU cINS NSFAR f arguments 

0 AF OC CASEW R ” : : cose on change mode 
4! 3; argument value 
0 #KCODE BASE,- 3 pase value 

00 4088 8F D0 #<KERNEL_COUNTER-1> : Limit value (number of entries 
0 > KCASE_BASE: 3 ood table base address for Ser INE “SERVICE 
ue P+} 
if 9 : pee table entries are made in the PSECT USER eens. pis? by 
0039 3 ocations of the OFF IN SERVICE macro. thet hree PSECTS 
Yt ; : USER KERNEL_DISPO,1,2 will be abutted in lexical order at (ink-time. 
ue 3 
0000000¢ -PSECT USER KERNEL DISP2.BYTE,NOWRT EXE .P 
000 BUG_ CHECK IVSSRVRQST,FATAL : Since ty chenge e mode code is validated 
004 : above, we should never get here 
le 


- 
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-SBTTL Intercept system service SSSI_USSK user system service 


“Funct tonal Description: 
routine sets we the interface to the real routines which 
orters che real work. 
Input Parameter 
R4 = Address of current PCB 


Output Parameters: 
RO = Completion Status Code ~ 


= 
Wr—-O 


SI_USSK,“M<R4> 
SSIK_START 3 Invoke routine in privilege library 


PUPAE BE 
MEO ODNAUE 
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i : - -SBTTL Intercept system service $SSI_USSU user system service 
11 3 Funct tonet Description: 
11 3 This routine sets up the interface to the real routines which 
11 $ porvere the real work. 
11 3 Input Parameters: 
11 4; See Argument List 
11 5 ; Output Parameters: 
11 96 3 RO = Completion Status Code 
i ie 
0000 1 , .ENTRY INT_SSI_USSU,“M<> 
6c 046 OD 13 CMPL #4, TAP)” ; Require to have 4 arguments 
7. 2 18 BNEQ UINSF ARG 3 Not 4 
5 6C 9A 1 MOVZBL (AP),R1 ; Get required argument count 
51 00000004 9F41 1 VAL a#6Ch1),R1 ; Compute byte count including arg count 
74 IFNORD R1,(AP),UACCVIO : Branch if arglist not readable 
OA 11 029 3 RB START + Ok 
028 77 UVACCVIO: 3; User access violation 
50 Oc 3C 0028 7 MOVZWL #SS$_ACCVIO,RO ; Set access violation status code 
0 : % RET : and return 
F 1 UINSFARG: ; Kernel insufficient arguments 
50 0114 8F 35 F ¢ MOVZWL #SS$_INSFARG,RO 3; Set access violation status code 
4 3 : 7 RET g and return 
035 5 START: 
10 AC DD 0035 $ PUSHL 16(AP) ; SAVE_MASK, the running state of 
0 ; all the user declared routines 
3 in different priorities before 
0 ; changing by USER_MASK, this value 
90 : is returned to the caller. 
Oc AC DD 00 4 PUSHL 12(AP) ; USER_ID, used for checking purpose 
0 ; :  in"SSE_START, this value is 
9 3 returned to the caller. 
08 AC OD 94 PUSHL 8(AP) : USER_ADDR, user cog tared routine 
— 395 : tobe called at interception time. 
04 AC ODD OOSE 9 PUSHL 4(AP) ; USER _SETUP_FLAGS has pyres (one byte 
4 9 : each for SETUP FLAG, USER PRIO, 
41 39 :  USER_MASK & USER_MODE). Oser 
41 9 3 sets up the status for declared 
rt : : : routine. 
08 BE 04 98 } 2 § a 89.04 .6(SP) :; Writability of USER_ID 
FFEO if cs rt : BR UACCVIO 
OC BE 04 4 2 6 2$: ecece $9.06 1215?) 3; Writabiltiy of SAVE_MASK 
FFD6 «3 2 8 Exe VACCVIO 
4 ? ; Check SETUP_FLAG (0-1) 
01 § 91 411 ds: CMPB (SP) #1 ; Check for legal setup flag 
18 ti¢ BLEQU $ : 0 - Disable, 1 - Enable 
0028 3 : ret BRw 00$ 
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20 415 A Check USER_PRIO (1-4) 


<tn 


01 O1AE 91 416 bs: CMPB- 1(SP), #1 i Check for legal priorit ; 
08 19 413 ass | (108 eee . 

06 O1A 1 41 CMPB 1(SP) #4 : 1 ree = User program in user mode ‘ 
8 1? $} gers 193 3 DEBUG in user mode $ 

421 108: 5 4 = Super DEBUG in user mode : 

OO1A 31 0068 42g BRY 1008 ae : 

E 424 : 

6— 425 : we don’ t het USER_MASK for we only take one bit value for $ 

; 4 $: 3 orto, | ts for prio. + % § bits for prio. 3, and 4 bits for prio. 4. 3 

; ? j : ta $$1_§ TART. Note: this is the way we return sesh walue back to user. é 

6E 409 ° : 

6E 450 ; xe Fe ps RAMOOE Si (3 ; 

03 «03 at 91 $f 431 12 (SP) , #PSLSC_USER ; Check for legal mode ; 
0 13 4 § gror 14$ 3 

0011 31 te) ? Z BRw 100$ 3; Only accept user mode 3 

077 435 ; Check USER_ID (0 OR 1-16) F 

10 O8 BE v1 0077 4 6 168: CPL 3B(s SP) #16 ; Check for Legal USER_ID value ; 
oon 8 070 ; 4 pceu BB 3: range: 0 to 16 3 

0 4 F 

p cat ; ALL checking is done, ready to call the routines to do the real work. é 

208: : 

00000000'GF 04 FB . te CALLS #4,G*SSIU_START 3 
04 ° rey RET : 

tt 446 1008: ; 

50 00 0° 2 st #0,R0 : 

C 46 F 

C 450 ; This routine is declared as the user rundown service. It gets called F 

C $3 3; at image rundown. Its purpose is to restore the system service vector : 

C 4 § 3; to its original state. This is done by calling the COPY _SAVED_SSV F 

C 453 ; routine in module RESETSSV. Note - this routine does not want to 3 

C 4654; restore the system service vector twice. It checks for this both : 

C 455 ; by checking to see whether there is are JSBs in the Syetes service r 

C $28 3; vector and also check ing a global flag that says whether we have 3 

: ? : changed the system service vector. J 

C £38 ELEANUP_SSV:: ; 

16 00000002'9F 91 $69 “CHPB. @4SYSSRUNDWN*+2,#OP$_JSB ; Has the system service. vector 3 
4 3 been changed? H, ; 

93 46 ; 6 will have put a is8 lnstruction : 

9 46 3 at SYS$anything*+2) 3 

OF SY 9 464 BNEQ 108 3; No, skip call which restores SSV : 
OO0O00000"EF OD 9 465 TSTL SSV_MUNGED_FLAG 3; Has the system service vector : 
98 4 § 3 been changed? : 

97 13 98 46 BEQL Hy 3; No, skip call which restores SSV : 
00000000‘ EF 0 re 90 4 3 CALLS #0,COPY_SAVED_SSV 3 Restore system service vector : 
0 AS 469 108 RSB ; 

ne 4 9 : 

A 47 ~END i 

vaitieeetaensintimsnaiinicinan L 
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S$S1_SYS_DISP - user system service dispatch 15-SEP-1984 :40:11 VAX/VMS Ma v04-00 p 1 
samt . ppm 37 3ee= 188s bose sde $8 aoe 3 


Symbol fable “SEP=- DEBUG. SRCJSSIDISP.MAR; 1 (2) 
BUGS IVSSRVRQST eeeeenee 8 x 
C SSV 0000008C RG 
COPY SAVED_SSV eenreree § X 
INT_SSI_USS 4 RG 
INT SSI_USSU 1 RG 
KACCVIO 98 a 
KCASE_BASE R 7 
KCODE BASE = 4 ; 
KERNEC_COUNTER = 
KERNEL _DISPATCH RG 7 
KERNEL_NARG R $ 
KINSF ARG R 
= oA R 7 
= 
PLVSC_TYP_CMOD = ; 
PSLSC"USER = 03 
SS$_ACCVIO = 
SS$_INSFARG = 00114 
SSIR_START eeneneee 0 
ee] 08sK 90000000 RG oe 
ee i-useu 00000008 Re Od 
SSV MUNGED_F LAG RROkRe Re x 3 
SAE ves seers, 
SYSSRONDWN eeeeeere = KX 0 
VACCVIO 449 4043 R 0 
UINSF ARG 4444 FR 0 
USER_NARG 0000000 R 0 
beer mom wore e een ee e 
! Psect synopsis ! 
Feewnewmace eee ewe + 
PSECT name Allocation PSECT No. Attributes 
- ABS . ( -»> 00 ¢ 0.) NOPIC USR CON ABS LCL NOSHR NOEXE NORD NOWRT NOVEC BYTE 
SABSS ( -») O1¢ 1.) NOPIC USR CON ABS LCL NOSHR EXE AD WRT NOVEC BYTE 
KERNEL_NARG ( mS § ( §°} PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER ( 1.) ( -) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
SSSTRANSFER_VECTOR ( 16.) Q046¢ 4.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC PAGE 
SER_KERNEL _DISP1 ( a 7 Ee Ben PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
SER- SERVICES ( H all $ ( §-) PIC USR CON REL LCL NOSHR EXE RD NOWRT VEC PAGE 
BEE ERNE! DI Seo ( ) ( “a PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
USER_KERNEL_DISP ( 165.) O08 ¢ 86.) PIC USR CON REL LCL NOSHR EXE RD NOWRT NOVEC BYTE 
tewrvnecewoanreanmnrowrenreseeocne ¢ 
: Performance indicators ! 
Phase Page faults CPU Time Elapsed Time 
Initialization 1 :00: 97 :00:01. 
Command processing 7 :00:00.74 :00:03. 
Pass 1 29 :00:09. 7:00:26. 
Symbol table sort :00:01. :00:05. 
Pass 2 1 :00:01.92 :00:06.84 
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SS1_SYS_DISP - user system service dispatch 15-SEP-1984 7:40:11 
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VAX=11 Macro Run Statistics 
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The working set Limit was 1350 pages. 
53089 bytes (104 pages) of virtual memory were used to buffer the intermediate code. 
There were 60 pages of symbol table space al nag to hold 1057 non-local and local symools. 


471 source Lines were read in Pass 1, producing 31 object records in Pass 2. 
17 pages of virtual memory were used to define 15 macros. 


Petr ane are oee see naasnececeanne 


! Macro Library statistics ! 


poeaeannasansrwramannrsamanrwe sowed 


Macro Library name Macros defined 
“B52 28DUACE: SYS.OBJJLIB.MLB;1 3 

$255$DUA28: CSYSLIBIJSTARLET.MLB;2 8 . 
TOTALS (all Libraries) 11° 


1104 GETS were required to define 11 macros. 
There were no errors, warnings or information messages. 
MACRO/LIS=L1S$:SSIDISP/OBJ=OBJ$:SSIDISP MSRC$:SSIDISP/UPDATE=(ENHS$:SSIDISP) *EXECML$/LIB 


AX/VMS Macro v04-00 Page 1 
DEBUG. SRCIJSSIDISP.MAR;1 ( 
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